{ "openapi": "3.0.0", "info": { "title": "Master Data API - v1", "description": "Master Data is a highly customizable VTEX database solution, which enables you to create applications. By default, Master Data is used to store and organize Customer data from your store. It features a powerful search engine, allowing you to store, search, expand, and customize data. Learn more about [Master Data v1](https://help.vtex.com/en/tutorial/master-data--4otjBnR27u4WUIciQsmkAw).\r\n\r\n## Index\r\n\r\n### Data Entities\r\n\r\nObtain information about the structure of the data entities.\r\n\r\n- `GET` [List data entities](https://developers.vtex.com/docs/api-reference/masterdata-api#get-/api/dataentities)\r\n- `GET` [Get data entity structure](https://developers.vtex.com/docs/api-reference/masterdata-api#get-/api/dataentities/-acronym-)\r\n\r\n### Documents\r\n\r\nCreate, update and retrieve documents.\r\n\r\n- `POST` [Create new document](https://developers.vtex.com/docs/api-reference/masterdata-api#post-/api/dataentities/-acronym-/documents)\r\n- `PUT` [Create document with custom ID or Update entire document](https://developers.vtex.com/docs/api-reference/masterdata-api#put-/api/dataentities/-acronym-/documents/-id-)\r\n- `PATCH` [Create or update partial document](https://developers.vtex.com/docs/api-reference/masterdata-api#patch-/api/dataentities/-acronym-/documents)\r\n- `GET` [Get document](https://developers.vtex.com/docs/api-reference/masterdata-api#get-/api/dataentities/-acronym-/documents/-id-)\r\n- `PUT` [Update entire document](https://developers.vtex.com/docs/api-reference/masterdata-api#put-/api/dataentities/-acronym-/documents/-id-)\r\n- `PATCH` [Update partial document](https://developers.vtex.com/docs/api-reference/masterdata-api#patch-/api/dataentities/-acronym-/documents/-id-)\r\n- `DELETE` [Delete document](https://developers.vtex.com/docs/api-reference/masterdata-api#delete-/api/dataentities/-acronym-/documents/-id-)\r\n\r\n### Customer profiles\r\n\r\nModify customer profiles in the CL entity.\r\n\r\n- `POST` [Create new customer profile](https://developers.vtex.com/docs/api-reference/masterdata-api#post-/api/dataentities/CL/documents)\r\n- `PATCH` [Update customer profile](https://developers.vtex.com/docs/api-reference/masterdata-api#patch-/api/dataentities/CL/documents/-id-)\r\n- `DELETE` [Delete customer profile](https://developers.vtex.com/docs/api-reference/masterdata-api#delete-/api/dataentities/CL/documents/-id-)\r\n\r\n### Addresses\r\n\r\nModify customer addresses in the AD entity.\r\n\r\n- `POST` [Create new customer address](https://developers.vtex.com/docs/api-reference/masterdata-api#post-/api/dataentities/AD/documents)\r\n- `PATCH` [Update customer address](https://developers.vtex.com/docs/api-reference/masterdata-api#patch-/api/dataentities/AD/documents/-id-)\r\n- `DELETE` [Delete customer address](https://developers.vtex.com/docs/api-reference/masterdata-api#delete-/api/dataentities/AD/documents/-id-)\r\n\r\n### Versions\r\n\r\nMaster Data documents are versioned. This means that, for each change, a new version is generated. The versions endpoints allow you to query the versions and also apply the state of a document to the most current version.\r\n\r\n- `GET` [List versions](https://developers.vtex.com/docs/api-reference/masterdata-api#get-/api/dataentities/-acronym-/documents/-id-/versions)\r\n- `GET` [Get version](https://developers.vtex.com/docs/api-reference/masterdata-api#get-/api/dataentities/-acronym-/documents/-id-/versions/-versionId-)\r\n- `PUT` [Put version](https://developers.vtex.com/docs/api-reference/masterdata-api#put-/api/dataentities/-acronym-/documents/-id-/versions/-versionId-)\r\n\r\n### Scroll\r\n\r\nDeveloped for external integration scenarios. If your collection is over 10.000 documents or you need to query the entire VTEX Master Data database, use these endpoints.\r\n\r\n- `GET` [Scroll documents](https://developers.vtex.com/docs/api-reference/masterdata-api#get-/api/dataentities/-acronym-/scroll)\r\n\r\n### Search\r\n\r\nQuery a collection of documents.\r\n\r\n- `GET` [Search documents](https://developers.vtex.com/docs/api-reference/masterdata-api#get-/api/dataentities/-acronym-/search)\r\n\r\n### Attachments\r\n\r\nUpload and download files.\r\n\r\n- `GET` [Retrieve attachment](https://developers.vtex.com/docs/api-reference/masterdata-api#get-/api/dataentities/-acronym-/documents/-id-/-field-/attachments/-file-name-)\r\n- `POST` [Save attachment](https://developers.vtex.com/docs/api-reference/masterdata-api#post-/api/dataentities/-acronym-/documents/-id-/-field-/attachments)\r\n\r\n### Clusters\r\n\r\nCheck if a particular document is in one or more clusters.\r\n\r\n- `POST` [Validate Document by Clusters](https://developers.vtex.com/docs/api-reference/masterdata-api#post-/api/dataentities/-acronym-/documents/-id-/clusters)\r\n\r\n### Score\r\n\r\nRecord and remove points in `Score2` type fields. Learn more about [Data entity field types](https://help.vtex.com/en/tutorial/creating-data-entity--tutorials_1265#understanding-the-types). \r\n\r\n- `PUT` [Put scores](https://developers.vtex.com/docs/api-reference/masterdata-api#put-/api/dataentities/-acronym-/documents/-id-/score)\r\n- `PUT` [Put score by field](https://developers.vtex.com/docs/api-reference/masterdata-api#put-/api/dataentities/-acronym-/documents/-id-/score/-field-name-)\r\n- `DELETE` [Delete score by field](https://developers.vtex.com/docs/api-reference/masterdata-api#delete-/api/dataentities/-acronym-/documents/-id-/score/-field-name-)\r\n", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://{accountName}.{environment}.com.br", "description": "VTEX server URL.", "variables": { "accountName": { "description": "Name of the VTEX account. Used as part of the URL.", "default": "apiexamples" }, "environment": { "description": "Environment to use. Used as part of the URL.", "enum": [ "vtexcommercestable" ], "default": "vtexcommercestable" } } } ], "paths": { "/api/dataentities": { "get": { "tags": [ "Data Entities" ], "summary": "List data entities", "description": "Retrieves the list of existing data entities in the store. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n| Dynamic Storage | Data entity | **List data entity** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Listdataentities", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Listdataentity" } }, "example": [ { "acronym": "SP", "name": "Sample", "primaryKeyType": "GUID", "allowGetAll": false }, { "acronym": "AD", "name": "Endereço", "primaryKeyType": "GUID", "allowGetAll": false }, { "acronym": "CL", "name": "Cliente", "primaryKeyType": "GUID", "allowGetAll": false } ] } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "Message": { "type": "string", "description": "Error message." } } }, "example": { "Message": "Unauthorized" } } } } } } }, "/api/dataentities/{acronym}": { "get": { "tags": [ "Data Entities" ], "summary": "Get data entity structure", "description": "Returns the data entity structure with its respective fields and data type. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n| Dynamic Storage | Data entity | **View data entity details** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getdataentitystructure", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "acronym", "in": "path", "description": "Data entity acronym.", "required": true, "style": "simple", "schema": { "type": "string", "example": "SP" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Getdataentityfields" }, "example": { "acronym": "SP", "name": "Sample", "primaryKeyType": "GUID", "allowGetAll": false, "fields": [ { "name": "updatedIn", "type": "Date and Time", "displayName": "Atualizado em", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": true }, { "name": "updatedBy", "type": "User Login", "displayName": "Atualizado por", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": true }, { "name": "Auto_Increment", "type": "Auto Increment", "displayName": "Auto increment", "isNullable": true, "isSearchable": false, "isFilter": false, "isInternal": false }, { "name": "Boolean", "type": "Boolean", "displayName": "Boolean", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "createdIn", "type": "Date and Time", "displayName": "Criado em", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": true }, { "name": "createdBy", "type": "User Login", "displayName": "Criado por", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": true }, { "name": "Currency", "type": "Currency", "displayName": "Currency", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "Date", "type": "Date", "displayName": "Date", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "Date_Time", "type": "Date and Time", "displayName": "Date and Time", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "Decimal", "type": "Decimal", "displayName": "Decimal", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "Email", "type": "Email", "displayName": "Email", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": false }, { "name": "dataEntityId", "type": "Varchar 10", "displayName": "Entidade de dados", "isNullable": false, "isSearchable": true, "isFilter": false, "isInternal": true }, { "name": "File", "type": "File", "displayName": "File", "isNullable": true, "isSearchable": false, "isFilter": false, "isInternal": false }, { "name": "auto_filter", "type": "Text", "displayName": "Filtro automático", "isNullable": true, "isSearchable": false, "isFilter": false, "isInternal": true }, { "name": "accountId", "type": "Varchar 50", "displayName": "ID da loja", "isNullable": false, "isSearchable": false, "isFilter": false, "isInternal": true }, { "name": "id", "type": "Varchar 100", "displayName": "Id do documento", "isNullable": false, "isSearchable": true, "isFilter": false, "isInternal": true }, { "name": "Integer", "type": "Integer", "displayName": "Integer", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "Long", "type": "Long", "displayName": "Long", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "accountName", "type": "Varchar 100", "displayName": "Nome da loja", "isNullable": false, "isSearchable": true, "isFilter": false, "isInternal": true }, { "name": "Percent", "type": "Percent", "displayName": "Percent", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "Relationship", "type": "Relationship", "displayName": "Relationship", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": false }, { "name": "Score2", "type": "Score2", "displayName": "Score2", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "followers", "type": "Text", "displayName": "Seguidores", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": true }, { "name": "tags", "type": "Text", "displayName": "Tags", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": true }, { "name": "Text", "type": "Text", "displayName": "Text", "isNullable": true, "isSearchable": false, "isFilter": false, "isInternal": false }, { "name": "Time", "type": "Time", "displayName": "Time", "isNullable": true, "isSearchable": false, "isFilter": false, "isInternal": false }, { "name": "lastInteractionIn", "type": "Date and Time", "displayName": "Ultima interação em", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": true }, { "name": "lastInteractionBy", "type": "User Login", "displayName": "Ultima interação por", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": true }, { "name": "URL", "type": "URL", "displayName": "URL", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "User_Login", "type": "User Login", "displayName": "User Login", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": false }, { "name": "Varchar10", "type": "Varchar 10", "displayName": "Varchar 10", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": false }, { "name": "Varchar100", "type": "Varchar 100", "displayName": "Varchar 100", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": false }, { "name": "Varchar50", "type": "Varchar 50", "displayName": "Varchar 50", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": false }, { "name": "Varchar750", "type": "Varchar 750", "displayName": "Varchar 750", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": false } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "Message": { "type": "string", "description": "Error message." } } }, "example": { "Message": "Unauthorized" } } } } } } }, "/api/dataentities/{acronym}/documents": { "post": { "tags": [ "Documents" ], "summary": "Create new document", "description": "Creates a new document with an ID automatically generated by VTEX, corresponding to a given data entity. The request body is a JSON object where the key is the name of the field.\r\n\r\n>ℹ️ You can use this request to create documents in any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update.\r\n\r\n## Custom field types\r\n\r\nThe table below presents the types of custom fields you can use when creating or updating documents in Master Data v1 and example values.\r\n\r\n| Field Type| Example value |\r\n| - | - |\r\n| Boolean | `true` |\r\n| Currency | `2.5` |\r\n| Date | `1992-11-17` |\r\n| Date_Time | `2016-09-14T19:21:01.3163733Z` |\r\n| Decimal | `2.5` |\r\n| Email | `meu@email.com` |\r\n| Integer | `1000000` |\r\n| Long | `1000000000` |\r\n| Percent | `85.42` |\r\n| Time | `23:50` |\r\n| URL | `https://www.vtex.com` |\r\n| Varchar10 | `Lorem ipsu` |\r\n| Varchar50 | `Lorem ipsum dolor sit amet, consectetur adipiscing` |\r\n| Varchar750 | `Lorem ipsum dolor sit amet, consectetur adipiscing elit...` |\r\n| Varchar100 | `Lorem ipsum dolor sit amet, consectetur adipiscing elit...` |\r\n| Relationship | `5eb31afb-7ab0-11e6-94b4-0a44686e393f` |\r\n| Text | `Lorem ipsum dolor sit amet, consectetur adipiscing elit...` |\r\n \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Createnewdocument", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Object with document fields and their respective values.", "additionalProperties": true, "properties": { "{fieldName}": { "type": "string", "description": "Field name.", "example": "{fieldValue}" } } }, "example": { "Boolean": true, "Currency": 2.5, "Date": "1992-11-17", "Date_Time": "2016-09-14T19:21:01.3163733Z", "Decimal": 2.5, "Email": "meu@email.com", "Integer": 1000000, "Long": 1000000000, "Percent": 85.42, "Time": "23:50", "URL": "http://www.vtex.com", "Varchar10": "Lorem ipsu", "Varchar50": "Lorem ipsum dolor sit amet, consectetur adipiscing", "Varchar750": "Lorem ipsum dolor sit amet, consectetur adipiscing elit...", "Varchar100": "Lorem ipsum dolor sit amet, consectetur adipiscing elit...", "Relationship": "5eb31afb-7ab0-11e6-94b4-0a44686e393f", "Text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit..." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdHrefDocumentID" }, "example": { "Id": "CL-be30ed0b-78ec-11ee-83ab-0eca8d1868e1", "Href": "http://apiexamples.vtexcommercestable.com.br/api/dataentities/CL/documents/be30ed0b-78ec-11ee-83ab-0eca8d1868e1", "DocumentId": "be30ed0b-78ec-11ee-83ab-0eca8d1868e1" } } } } } }, "patch": { "tags": [ "Documents" ], "summary": "Create partial document", "description": "Creates a partial document, sending only some of the fields.\r\n\r\n> You can use this request to create documents in any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Createorupdatepartialdocument", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Unique identifier of the document to be created.", "example": "4e4c55ac-e491-11e6-94f4-0ac138d2d42e" }, "{fieldName}": { "type": "string", "description": "Field(s) to be filled in and its respective value(s).", "example": "{fieldValue}" } } }, "example": { "id": "4e4c55ac-e491-11e6-94f4-0ac138d2d42e", "addressName": "4726026151251" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdHrefDocumentID" }, "example": { "Id": "CL-be30ed0b-78ec-11ee-83ab-0eca8d1868e1", "Href": "http://apiexamples.vtexcommercestable.com.br/api/dataentities/CL/documents/be30ed0b-78ec-11ee-83ab-0eca8d1868e1", "DocumentId": "be30ed0b-78ec-11ee-83ab-0eca8d1868e1" } } } } } } }, "/api/dataentities/{acronym}/documents/{id}": { "get": { "tags": [ "Documents" ], "summary": "Get document", "description": "Retrieves a document.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getdocument", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" }, "example": { "id": "2f5dde81-1613-11ea-82ee-12f868feb457", "accountId": "a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2", "accountName": "apiexamples", "dataEntityId": "AS" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "description": "Error response body.", "type": "object", "properties": { "Message": { "description": "Error message.", "type": "string" } } }, "example": { "Message": "Cannot read private fields" } } } } } }, "put": { "tags": [ "Documents" ], "summary": "Create document with custom ID or update entire document", "description": "Creates a new document with a custom ID, or updates an entire document if there is already a document with the informed ID.\r\n\r\n>ℹ️ You can use this request to create or update documents in any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update.\r\n\r\n## Custom field types\r\n\r\nThe table below presents the types of custom fields you can use when creating or updating documents in Master Data v1 and example values.\r\n\r\n| Field Type| Example value |\r\n| - | - |\r\n| Boolean | `true` |\r\n| Currency | `2.5` |\r\n| Date | `1992-11-17` |\r\n| Date_Time | `2016-09-14T19:21:01.3163733Z` |\r\n| Decimal | `2.5` |\r\n| Email | `meu@email.com` |\r\n| Integer | `1000000` |\r\n| Long | `1000000000` |\r\n| Percent | `85.42` |\r\n| Time | `23:50` |\r\n| URL | `https://www.vtex.com` |\r\n| Varchar10 | `Lorem ipsu` |\r\n| Varchar50 | `Lorem ipsum dolor sit amet, consectetur adipiscing` |\r\n| Varchar750 | `Lorem ipsum dolor sit amet, consectetur adipiscing elit...` |\r\n| Varchar100 | `Lorem ipsum dolor sit amet, consectetur adipiscing elit...` |\r\n| Relationship | `5eb31afb-7ab0-11e6-94b4-0a44686e393f` |\r\n| Text | `Lorem ipsum dolor sit amet, consectetur adipiscing elit...` |\r\n \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Updateentiredocument", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Object with document fields and their respective values.", "additionalProperties": true, "properties": { "{fieldName}": { "type": "string", "description": "Field name and value.", "example": "{fieldValue}" } } }, "example": { "Boolean": true, "Currency": 2.5, "Date": "1992-11-17", "Date_Time": "2016-09-14T19:21:01.3163733Z", "Decimal": 2.5, "Email": "meu@email.com", "Integer": 1000000, "Long": 1000000000, "Percent": 85.42, "Time": "23:50", "URL": "http://www.vtex.com", "Varchar10": "Lorem ipsu", "Varchar50": "Lorem ipsum dolor sit amet, consectetur adipiscing", "Varchar750": "Lorem ipsum dolor sit amet, consectetur adipiscing elit...", "Varchar100": "Lorem ipsum dolor sit amet, consectetur adipiscing elit...", "Relationship": "5eb31afb-7ab0-11e6-94b4-0a44686e393f", "Text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit..." } } }, "required": true }, "responses": { "204": { "description": "No Content" } } }, "patch": { "tags": [ "Documents" ], "summary": "Update partial document", "description": "Updates a subset of fields of a document, without impacting the other fields.\r\n\r\n>ℹ️ You can use this request to update documents in any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Updatepartialdocument", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Object with the fields to be updated and their respective values." }, "example": { "addressName": "4726026151253" } } }, "required": true }, "responses": { "204": { "description": "No Content" } } }, "delete": { "tags": [ "Documents" ], "summary": "Delete document", "description": "Deletes a document. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Deletedocument", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" } ], "responses": { "204": { "description": "No Content" } } } }, "/api/dataentities/{acronym}/documents/{id}/versions": { "get": { "tags": [ "Versions" ], "summary": "List versions", "description": "Lists all versions of a document. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Listversions", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Listversion" } }, "example": [ { "id": "_EAR0cJ7XB5k5grnmm0zeKGlVvVM9WCPV_", "date": "2016-10-18T16:53:32+00:00" }, { "id": "_E5SH9WXVvhPBNnbQtYAAGqrIysIeNYhy_", "date": "2016-09-08T20:11:42+00:00" }, { "id": "_cwVfOG7S6XeAiDBhNpLiJM1cwRiJcvdp_", "date": "2016-07-14T00:36:36+00:00" } ] } } } } } }, "/api/dataentities/{acronym}/documents/{id}/versions/{versionId}": { "get": { "tags": [ "Versions" ], "summary": "Get version", "description": "Returns the version of a document. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getversion", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" }, { "name": "versionId", "in": "path", "description": "Unique identifier of the version to retrieve.", "required": true, "style": "simple", "schema": { "type": "string", "example": "_X58kLameckHYRuBMUbaimlhwqslsrrwT_" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Getversion" }, "example": { "id": "version-id", "author": "user-id", "document": { "id": "2f5dde81-1613-11ea-82ee-12f868feb457", "accountId": "a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2", "accountName": "apiexamples", "dataEntityId": "AS" } } } } } } }, "put": { "tags": [ "Versions" ], "summary": "Update version", "description": "Updates the version of a document. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Putversion", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" }, { "name": "versionId", "in": "path", "description": "Unique identifier of the version to update.", "required": true, "style": "simple", "schema": { "type": "string", "example": "_X58kLameckHYRuBMUbaimlhwqslsrrwT_" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdHref" }, "example": { "Id": "CL-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://{{accountName}}.vtexcommercestable.com.br/api/dataentities/CL/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } }, "304": { "description": "Not modified. This response happens when the `versionId` informed in the path already corresponds to the current version of the document." } } } }, "/api/dataentities/{acronym}/scroll": { "get": { "tags": [ "Scroll" ], "summary": "Scroll documents", "description": "Returns a list of documents according to query parameter filters. If you need to query the entire database, or your collection is over 10000 documents, use this endpoint.\r\n\r\nIn the first request, the `X-VTEX-MD-TOKEN` token will be obtained in the response header. This token must be passed to the next request in the `_token` query string parameter. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.\r\n\r\nAfter the token is obtained, it is no longer necessary to send the filter or document size per page parameters. You only need to resend the token until the document collection is empty.\r\n\r\n### First request example:\r\n```\r\n/dataentities/CL/scroll?isCluster=true&_size=250&_fields=email,firstName\r\n```\r\n\r\nTo inform the number of documents per request, use the query string parameter `_size`, which has the maximum value of 1000.\r\n\r\nAfter the first request, retrieve the token in the header `X-VTEX-MD-TOKEN` and make the next requests.\r\n\r\n### Example of subsequent requests:\r\n```\r\n/dataentities/CL/scroll?_token={tokenValue}\r\n```\r\n\r\n>ℹ️ Learn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n## Query examples\r\n\r\n\r\n| **Filter Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/CL\/scroll?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/CL\/scroll?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/CL\/scroll?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Numeric field range** | `\/dataentities\/CL\/scroll?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/CL\/scroll?firstName=*Maria*` |\r\n| **Null values** | `\/dataentities\/CL\/scroll?_where=firstName is null` |\r\n| **Non-null values** | `\/dataentities\/CL\/scroll?_where=firstName is not null` |\r\n| **Difference** | `\/dataentities\/CL\/scroll?_where=firstName<>maria` |\r\n| **Greater than** | `\/dataentities\/CL\/scroll?_where=number>5` |\r\n| **Less than** | `\/dataentities\/CL\/scroll?_where=date<2001-01-01` |\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens, you will receive an error with status code `429`.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Scrolldocuments", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/fields" }, { "name": "_where", "in": "query", "description": "Defines a condition the document must comply with. When referring to fields, you can use a nested field up to the first level (e.g. `wishlistProduct.productName`).", "required": false, "style": "form", "schema": { "type": "string", "example": "firstName is not null" } }, { "name": "_sort", "in": "query", "description": "Defines sorting mode in two parts. The first part is the name of the field you want to sort by. It can be a nested field up to the first level (e.g. `wishlistProduct.productName`). In the second part, use `ASC` for ascending order or `DESC` for descending order.", "required": false, "style": "form", "schema": { "type": "string", "example": "firstName ASC" } }, { "name": "_size", "in": "query", "description": "Maximum amount of documents returned per request. The maximum value you can set is `1000`.", "required": false, "style": "form", "schema": { "type": "string", "example": "10" } }, { "name": "_token", "in": "query", "description": "Value of the `X-VTEX-MD-TOKEN` token obtained in the response header of the first request, necessary on subsequent requests to continue scrolling through documents. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.", "required": false, "style": "form", "schema": { "type": "string", "example": "123456" } } ], "responses": { "200": { "description": "OK", "headers": { "X-VTEX-MD-TOKEN": { "schema": { "type": "string", "description": "Scroll token, which must be informed in the `_token` query parameter in the subsequent requests. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer." } }, "REST-Content-Total": { "schema": { "type": "string", "description": "Total amount of documents corresponding to the query." } } }, "content": { "application/json": { "schema": { "type": "array", "description": "List of documents.", "items": { "type": "object", "description": "Object representing each document.", "properties": { "additionalProperties": { "type": "string", "description": "Custom properties." }, "id": { "type": "string", "description": "Unique identifier of the document." }, "accountId": { "type": "string", "description": "Unique identifier of the account." }, "accountName": { "type": "string", "description": "Account name." }, "dataEntityId": { "type": "string", "description": "Two-letter string that identifies the data entity." } } } }, "example": [ { "id": "2f5dde81-1613-11ea-82ee-12f868feb457", "accountId": "a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2", "accountName": "apiexamples", "dataEntityId": "AS" }, { "id": "3b3a3fc9-164b-11ea-82ee-121449f60ecb", "accountId": "a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2", "accountName": "apiexamples", "dataEntityId": "AS" } ] } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "description": "Response body with error message.", "properties": { "Message": { "description": "Error message." } } }, "example": { "Message": "Maximum simultaneous scrolls rate exceeded (10)" } } } }, "429": { "description": "Too Many Requests. Wildcard queries temporarily blocked due to excessive usage. Consider adjusting your code to remove them or reduce the rate of search requests with wildcards (*). This temporary block may also be due to excessive use of requests with the parameter `keyword`." } } } }, "/api/dataentities/{acronym}/search": { "get": { "tags": [ "Search" ], "summary": "Search documents", "description": "Retrieves Master Data v1 documents' information, while choosing which fields will be returned and filtering documents by specific fields.\r\n\r\n>ℹ️ Learn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api) and [Querying documents in Master Data v1](https://developers.vtex.com/docs/guides/querying-documents-in-master-data-v1).\r\n\r\n## Query examples\r\n\r\n\r\n| **Filter Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/CL\/search?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/CL\/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/CL\/search?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Numeric field range** | `\/dataentities\/CL\/search?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/CL\/search?firstName=*Maria*` |\r\n| **Null values** | `\/dataentities\/CL\/search?_where=firstName is null` |\r\n| **Non-null values** | `\/dataentities\/CL\/search?_where=firstName is not null` |\r\n| **Difference** | `\/dataentities\/CL\/search?_where=firstName<>maria` |\r\n| **Greater than** | `\/dataentities\/CL\/search?_where=number>5` |\r\n| **Less than** | `\/dataentities\/CL\/search?_where=date<2001-01-01` |\n\r\n\r>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `503`. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Searchdocuments", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "REST-Range", "in": "header", "description": "Specifies the range of documents to be returned in the response. The value should follow the format `resources={x}-{y}`, where:\n* `x`: Index of the first document in the returned array.\n* `y`: Index of the last document in the returned array + 1.\n\nThis field controls pagination by defining the subset of documents to be retrieved. The maximum number of documents returned per query is limited to 100.\nFor example, `resources=0-10` returns the first 10 documents.", "required": true, "style": "simple", "schema": { "type": "string", "example": "resources=0-10" } }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/fields" }, { "name": "_where", "in": "query", "description": "Defines a condition the document must comply with. When referring to fields, you can use a nested field up to the first level (e.g. `wishlistProduct.productName`).", "required": false, "style": "form", "schema": { "type": "string", "example": "firstName is not null" } }, { "name": "_sort", "in": "query", "description": "Defines sorting mode in two parts. The first part is the name of the field you want to sort by. It can be a nested field up to the first level (e.g. `wishlistProduct.productName`). In the second part, use `ASC` for ascending order or `DESC` for descending order.", "required": false, "style": "form", "schema": { "type": "string", "example": "firstName ASC" } } ], "responses": { "200": { "description": "OK", "headers": { "REST-Content-Range": { "schema": { "type": "string", "description": "Indicates the range of documents returned in the current response, as well as the total number of documents available in the dataset. The value follows the format `resources={x}-{y}/{total}`, where:\n* `x`: Index of the first document in the returned array.\n* `y`: Index of the last document in the returned array + 1.\n* `total`: Total number of documents that match the query.\nFor example, `resources=0-10/98` indicates that documents from 0 to 9 are returned out of a total of 98 matching documents.", "example": "resources=0-10/98" } } }, "content": { "application/json": { "schema": { "type": "array", "description": "List of documents.", "items": { "type": "object", "description": "Object representing each document.", "properties": { "additionalProperties": { "type": "string", "description": "Custom properties." }, "id": { "type": "string", "description": "Unique identifier of the document." }, "accountId": { "type": "string", "description": "Unique identifier of the account." }, "accountName": { "type": "string", "description": "Account name." }, "dataEntityId": { "type": "string", "description": "Two-letter string that identifies the data entity." } } } }, "example": [ { "id": "2f5dde81-1613-11ea-82ee-12f868feb457", "accountId": "a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2", "accountName": "apiexamples", "dataEntityId": "AS" }, { "id": "3b3a3fc9-164b-11ea-82ee-121449f60ecb", "accountId": "a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2", "accountName": "apiexamples", "dataEntityId": "AS" } ] } } }, "503": { "description": "Service Unavailable. Wildcard queries temporarily blocked due to excessive usage. Consider adjusting your code to remove them or reduce the rate of search requests with wildcards (*). This temporary block may also be due to excessive use of requests with the parameter `keyword`." } } } }, "/api/dataentities/{acronym}/documents/{id}/{field}/attachments/{file-name}": { "get": { "tags": [ "Attachments" ], "summary": "Retrieve attachment", "description": "Retrieves a file that had been previously saved in a field of type `File`.\r\n\r\n>⚠️ Make sure to include the file extension in the name, like in this example: `/api/dataentities/CL/documents/123/file/attachments/image.png`. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Retrieveattachment", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" }, { "name": "field", "in": "path", "description": "Name of the field where the file is saved, as it appears on VTEX Admin.", "required": true, "style": "simple", "schema": { "type": "string", "example": "image" } }, { "name": "file-name", "in": "path", "description": "File name and extension.", "required": true, "style": "simple", "schema": { "type": "string", "example": "image.png" } } ], "responses": { "200": { "description": "OK", "content": { "image/jpg": { "schema": { "type": "string", "format": "binary", "description": "Image file." } } } } } } }, "/api/dataentities/{acronym}/documents/{id}/{field}/attachments": { "post": { "tags": [ "Attachments" ], "summary": "Save attachment", "description": "Saves a file in a field of type `File`. Learn more about [Data entity field types](https://help.vtex.com/en/tutorial/creating-data-entity--tutorials_1265#understanding-the-types).`\n\r\n\r> You can upload more than one file. Just add a new field in the `form-data` with type `File`. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Saveattachment", "parameters": [ { "$ref": "#/components/parameters/Content-Type-img" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" }, { "name": "field", "in": "path", "description": "Name of the field to attach the file to, as it appears in VTEX Admin.", "required": true, "style": "simple", "schema": { "type": "string", "example": "profilePicture" } } ], "requestBody": { "content": { "multipart/form-data": { "encoding": {}, "schema": { "required": [ "file" ], "type": "object", "properties": { "file": { "type": "array", "description": "Files to be uploaded.", "items": { "type": "string", "format": "binary", "description": "File to be uploaded.", "example": "image.jpg" } } } } } }, "required": false }, "responses": { "204": { "description": "No Content" } } } }, "/api/dataentities/{acronym}/documents/{id}/clusters": { "post": { "tags": [ "Clusters" ], "summary": "Validate document by clusters", "description": "Validate documents by clusters.\n\r\n\r> Learn more about Master Data [clusters](https://help.vtex.com/en/tutorial/how-can-i-create-cluster-of-customers--frequentlyAskedQuestions_1724). \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "ValidateDocumentbyClusters", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "Array of clusters.", "items": { "type": "object", "description": "Cluster information.", "properties": { "name": { "type": "string", "description": "Cluster validation rule name.", "example": "male" }, "rule": { "type": "string", "description": "Cluster validation rule.", "example": "gender=male" } } } }, "example": [ { "name": "male", "rule": "gender=male" }, { "name": "complex", "rule": "((gender=male AND percent=0.35) AND any is null) AND (name=*go*)" }, { "name": "complex2", "rule": "((gender=male AND percent=0.35) AND any is not null) OR (name=*go*)" }, { "name": "createdIn", "rule": "createdIn between 2015-10-28 AND 2015-10-30" } ] } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/dataentities/{acronym}/documents/{id}/score": { "put": { "tags": [ "Score" ], "summary": "Update scores", "description": "Updates the score of more than one `Score2` type field and more than one key. Learn more about [Data entity field types](https://help.vtex.com/en/tutorial/creating-data-entity--tutorials_1265#understanding-the-types). \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Putscores", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PutscoresRequest" } }, "example": [ { "field": "carttag", "key": "Payment", "point": 1, "until": "10m" }, { "field": "scoretest", "key": "Point 1", "point": 1, "until": "1d" } ] } }, "required": true }, "responses": { "204": { "description": "No Content" } } } }, "/api/dataentities/{acronym}/documents/{id}/score/{field-name}": { "put": { "tags": [ "Score" ], "summary": "Update score by field", "description": "Updates the score of a specific `Score2` type field. Learn more about [Data entity field types](https://help.vtex.com/en/tutorial/creating-data-entity--tutorials_1265#understanding-the-types). \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Putscorebyfield", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "name": "id", "in": "path", "description": "Unique identifier of the document.", "required": true, "style": "simple", "schema": { "type": "string", "example": "SP-b818cbda-e489-11e6-94f4-0ac138d2d42e" } }, { "name": "field-name", "in": "path", "description": "Name of the field to score.", "required": true, "style": "simple", "schema": { "type": "string", "example": "carttag" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutscorebyfieldRequest" }, "example": { "key": "first key", "point": 1, "until": "10m" } } }, "required": true }, "responses": { "204": { "description": "No Content" } } }, "delete": { "tags": [ "Score" ], "summary": "Delete score by field", "description": "Removes a key from a specific `Score2` type field. Learn more about [Data entity field types](https://help.vtex.com/en/tutorial/creating-data-entity--tutorials_1265#understanding-the-types). \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Deletescorebyfield", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" }, { "name": "field-name", "in": "path", "description": "Name of the field to remove a key from.", "required": true, "style": "simple", "schema": { "type": "string", "example": "carttag" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletescorebyfieldRequest" }, "example": { "key": "first key" } } }, "required": true }, "responses": { "204": { "description": "No Content" } } } }, "/api/dataentities/CL/documents": { "post": { "tags": [ "Customer profiles" ], "summary": "Create new customer profile", "description": "Creates new customer profile.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "CreateNewCustomerProfilev2", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/_schema" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createUpdateProfileRequests" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "CL-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/CL/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } } } }, "/api/dataentities/CL/documents/{id}": { "patch": { "tags": [ "Customer profiles" ], "summary": "Update customer profile", "description": "Partially updates a customer profile.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "UpdateCustomerProfile", "parameters": [ { "$ref": "#/components/parameters/_schema" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createUpdateProfileRequests" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "CL-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/CL/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } } }, "delete": { "tags": [ "Customer profiles" ], "summary": "Delete customer profile", "description": "Deletes a customer profile. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "DeleteCustomerProfile", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" } ], "responses": { "204": { "description": "No Content" } } } }, "/api/dataentities/AD/documents": { "post": { "tags": [ "Addresses" ], "summary": "Create new customer address", "description": "Creates new customer address. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "CreateNewCustomerAddress", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/_schema" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createUpdateAddressRequests" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "AD-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/AD/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } } } }, "/api/dataentities/AD/documents/{id}": { "patch": { "tags": [ "Addresses" ], "summary": "Update customer address", "description": "Partially updates a customer address.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "UpdateCustomerAddress", "parameters": [ { "$ref": "#/components/parameters/_schema" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createUpdateAddressRequests" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "AD-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/AD/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } } }, "delete": { "tags": [ "Addresses" ], "summary": "Delete customer address", "description": "Deletes a customer address. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "DeleteCustomerAD", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" } ], "responses": { "204": { "description": "No Content" } } } } }, "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ], "components": { "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey", "description": "Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)." }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken", "description": "Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)." }, "VtexIdclientAutCookie": { "type": "apiKey", "in": "header", "name": "VtexIdclientAutCookie", "description": "[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours." } }, "parameters": { "Content-Type": { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, "Content-Type-img": { "name": "Content-Type", "in": "header", "description": "Type of the content being sent. If you are uploading an image, use `image/jpg` or `image/png`. When using JavaScript, use `multipart/form-data`.", "required": true, "style": "simple", "schema": { "type": "string", "example": "image/jpg" } }, "Accept": { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/vnd.vtex.ds.v10+json" } }, "acronym": { "name": "acronym", "in": "path", "description": "Two-letter string that identifies the data entity.", "required": true, "style": "simple", "schema": { "type": "string", "example": "SP" } }, "id": { "name": "id", "in": "path", "description": "Unique identifier of the document.", "required": true, "style": "simple", "schema": { "type": "string", "example": "SP-b818cbda-e489-11e6-94f4-0ac138d2d42e" } }, "fields": { "name": "_fields", "in": "query", "description": "Names of the fields that will be returned per document, separated by a comma `,`. It is possible to fetch all fields using `_all` as the value of this query parameter. However, in order to avoid permission errors, we strongly recommend informing only the names of the exact fields that will be used.", "required": false, "style": "form", "schema": { "type": "string", "example": "email,firstName,document" } }, "_schema": { "name": "_schema", "in": "query", "description": "Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with. This field is required when using `_where` or `_fields` query parameters.", "required": false, "style": "form", "schema": { "type": "string", "example": "schema" } } }, "schemas": { "Listdataentity": { "title": "Listdataentity", "required": [ "acronym", "name", "primaryKeyType", "allowGetAll" ], "type": "object", "description": "Data entity information.", "properties": { "acronym": { "title": "acronym", "type": "string", "description": "Two-letter string that identifies the data entity." }, "name": { "title": "name", "type": "string", "description": "Data entity name." }, "primaryKeyType": { "title": "primaryKeyType", "type": "string", "description": "Primary key type." }, "allowGetAll": { "title": "allowGetAll", "type": "boolean", "description": "Defines if it will be allowed to retrieve all fields from documents from this data entity at once using the [Get document](https://developers.vtex.com/docs/api-reference/masterdata-api#get-/api/dataentities/-acronym-/documents/-id-) endpoint (`true`) or not (`false`)." } } }, "Getdataentityfields": { "title": "Data entity structure", "required": [ "acronym", "name", "primaryKeyType", "allowGetAll", "fields" ], "type": "object", "description": "Data entity structure.", "properties": { "acronym": { "$ref": "#/components/schemas/Listdataentity/properties/acronym" }, "name": { "$ref": "#/components/schemas/Listdataentity/properties/name" }, "primaryKeyType": { "$ref": "#/components/schemas/Listdataentity/properties/primaryKeyType" }, "allowGetAll": { "$ref": "#/components/schemas/Listdataentity/properties/allowGetAll" }, "fields": { "title": "fields", "type": "array", "description": "List of fields that documents from the given data entity have.", "items": { "$ref": "#/components/schemas/Field" } } } }, "Field": { "title": "Field", "description": "Field information.", "required": [ "name", "type", "displayName", "isNullable", "isSearchable", "isFilter", "isInternal" ], "type": "object", "properties": { "name": { "type": "string", "description": "Field name." }, "type": { "type": "string", "description": "Field type." }, "displayName": { "type": "string", "description": "Field display name." }, "isNullable": { "type": "boolean", "description": "Defines whether the field is nullable (`true`) or not (`false`)." }, "isSearchable": { "type": "boolean", "description": "Defines whether the field is searchable (`true`) or not (`false`)." }, "isFilter": { "type": "boolean", "description": "Defines whether the field is a filter (`true`) or not (`false`)." }, "isInternal": { "type": "boolean", "description": "Defines whether the field is for internal use only (`true`) or not (`false`)." } } }, "IdHrefDocumentID": { "type": "object", "description": "Document information.", "properties": { "Id": { "type": "string", "description": "ID of the document that was created, with data entity prefix." }, "Href": { "type": "string", "description": "Document reference URL." }, "DocumentId": { "type": "string", "description": "Unique identifier of the document." } } }, "IdHref": { "title": "IdHref", "required": [ "Id", "Href" ], "type": "object", "description": "Document information.", "properties": { "Id": { "type": "string", "description": "ID of the document that was created, with data entity prefix." }, "Href": { "type": "string", "description": "Document reference URL." } } }, "PutscoresRequest": { "title": "PutscoresRequest", "required": [ "field", "key", "point", "until" ], "type": "object", "description": "Score information.", "properties": { "field": { "type": "string", "description": "Field name.", "example": "carttag" }, "key": { "type": "string", "description": "Key name.", "example": "Payment" }, "point": { "type": "integer", "format": "int32", "description": "Amount of points to be added to the score.", "example": 1 }, "until": { "type": "string", "description": "Amount of time the added points will be valid for.", "example": "10m" } } }, "PutscorebyfieldRequest": { "title": "PutscorebyfieldRequest", "required": [ "key", "point", "until" ], "type": "object", "description": "Request body object to update score.", "properties": { "key": { "type": "string", "description": "Key name.", "example": "Payment" }, "point": { "type": "integer", "format": "int32", "description": "Amount of points to be added to the score.", "example": 1 }, "until": { "type": "string", "description": "Amount of time the added points will be valid for.", "example": "10m" } } }, "DeletescorebyfieldRequest": { "title": "DeletescorebyfieldRequest", "required": [ "key" ], "type": "object", "description": "Request body object to delete score.", "properties": { "key": { "type": "string", "description": "Key name.", "example": "Payment" } } }, "Listversion": { "title": "Listversion", "required": [ "id", "date" ], "type": "object", "description": "Version information.", "properties": { "id": { "type": "string", "description": "Unique identifier of the version." }, "date": { "type": "string", "description": "Date when the version was created, in ISO 8601 format." } } }, "Getversion": { "title": "Getversion", "required": [ "id", "author", "document" ], "type": "object", "description": "Version information.", "properties": { "id": { "type": "string", "description": "Unique identifier of the version." }, "author": { "type": "string", "description": "Unique identifier of the user who created the version." }, "document": { "$ref": "#/components/schemas/Document" } } }, "Document": { "title": "Document", "required": [ "id", "dataEntityId", "accountId", "accountName" ], "type": "object", "description": "Object representing each document.", "properties": { "{customProperty}": { "type": "string", "description": "Custom property." }, "id": { "type": "string", "description": "Unique identifier of the document." }, "accountId": { "type": "string", "description": "Unique identifier of the account." }, "accountName": { "type": "string", "description": "Account name." }, "dataEntityId": { "type": "string", "description": "Two-letter string that identifies the data entity." } } }, "createUpdateProfileRequests": { "type": "object", "description": "Request body object.", "properties": { "email": { "type": "string", "description": "Client email address.", "example": "clark.kent@examplemail.com", "nullable": true }, "firstName": { "type": "string", "description": "Client first name.", "example": "Clark", "nullable": true }, "lastName": { "type": "string", "description": "Client last name.", "example": "Kent", "nullable": true }, "phone": { "type": "string", "description": "Client telephone number.", "example": "+12025550195", "nullable": true }, "documentType": { "type": "string", "description": "Client document type.", "example": "CPF", "nullable": true }, "document": { "type": "string", "description": "Client document.", "example": "12345678900", "nullable": true }, "isCorporate": { "type": "boolean", "description": "Indicates whether client is corporate.", "example": false, "nullable": true }, "isNewsletterOptIn": { "type": "boolean", "description": "Indicates whether client otped to receive the store newsletter (`true`) or not (`false`).", "example": false, "nullable": true }, "localeDefault": { "type": "string", "description": "Default locale, used to set store language and currency, for example.", "example": "en-US", "nullable": true } } }, "createUpdateAddressRequests": { "type": "object", "description": "Request body object.", "properties": { "addressName": { "type": "string", "description": "Address name.", "example": "My house", "nullable": true }, "addressType": { "type": "string", "description": "Type of address. For example, `Residential` or `Pickup`, among others.", "example": "residential", "nullable": true }, "receiverName": { "type": "string", "description": "Name of the person who is going to receive the order.", "example": "Clark Kent.", "nullable": true }, "city": { "type": "string", "description": "City of the shipping address.", "example": "Rio de Janeiro", "nullable": true }, "state": { "type": "string", "description": "State of the shipping address.", "example": "Rio de Janeiro", "nullable": true }, "country": { "type": "string", "description": "Three letter ISO code of the country of the shipping address.", "example": "BRA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal Code.", "example": "12345-000", "nullable": true }, "street": { "type": "string", "description": "Street of the address.", "example": "Praia de Botafogo", "nullable": true }, "number": { "type": "string", "description": "Number of the building, house or apartment in the shipping address.", "example": "300", "nullable": true }, "neighborhood": { "type": "string", "description": "Neighborhood of the address.", "example": "Botafogo", "nullable": true }, "complement": { "type": "string", "description": "Complement to the shipping address in case it applies.", "example": "3rd floor", "nullable": true }, "reference": { "type": "string", "description": "Complement that might help locate the shipping address more precisely in case of delivery.", "example": "Grey building", "nullable": true }, "userId": { "type": "string", "description": "ID of the customer to whom the address belongs.", "example": "7e03m794-a33a-11e9-84rt6-0adfa64s5a8e", "nullable": true } } }, "documentResponse": { "required": [ "Id", "Href" ], "type": "object", "description": "Response body object.", "properties": { "Id": { "type": "string", "description": "ID of the document that was created or updated." }, "Href": { "type": "string", "description": "Document reference URL." } } } } }, "tags": [ { "name": "Data Entities" }, { "name": "Documents" }, { "name": "Customer profiles" }, { "name": "Addresses" }, { "name": "Versions" }, { "name": "Scroll" }, { "name": "Search" }, { "name": "Attachments" }, { "name": "Clusters" }, { "name": "Score" } ] }